<h2>DESCRIPTION</h2>

The <em><a href="r.in.lidar.html">r.in.lidar</a></em> module
is very similar to the <em>r3.in.lidar</em> module and many parts of
its documentation apply also for <em>r3.in.lidar</em>.

<p>
<img src="r3_in_lidar.png">
<p>
<em>
    Figure: Proportional count of points per 3D cell. When 50% of all
    points in a vertical column fall into a given 3D cell, the value
    is 0.5. Here, the green color was assigned to 0.5, red to 1 and
    yellow to 0. The figure shows vertical slices and green color
    indicates high vegetation while red color indicates bare ground.
</em>
<!--
0% 255:255:100
50% green
100% red
-->


<h2>NOTES</h2>

<ul>
    <li>
        This module is new and partially experimental. Please don't rely
        on its interface and be critical towards its outputs.
        Please report issues on the mailing list or in the bug tracker.
    <li>
        No reprojection is performed, you need to reproject ahead or
        use GRASS Location which has the right coordinate system
        which fits with the data.
    <li>
        Some temporary maps are created but not cleaned up. Use of
        <b>--overwrite</b> might be necessary even when not desired.
    <li>
        Expects points to have intensity and causing random (undefined)
        result for related outputs (<b>sum, mean, proportional_sum</b>)
        when the intensity is not present but the outputs were requested.
</ul>


<h2>EXAMPLES</h2>


<h3>Basic import of the data</h3>

Set the region according to a 2D raster and adding 3D minimum
(bottom), maximum (top) and vertical (top-bottom) resolution.

<div class="code"><pre>
g.region rast=secref b=80 t=160 tbres=5 -p3
</pre></div>

Now, <em>r3.in.lidar</em> will create the 3D raster of the size
given by the computation region:

<div class="code"><pre>
r3.in.lidar input=points.las n=points_n sum=points_sum \
    mean=points_mean proportional_n=points_n_prop \
    proportional_sum=points_sum_prop
</pre></div>


<h3>Point density vertical structure reduced to the terrain</h3>

Create ground raster:

<div class="code"><pre>
r.in.lidar input=points.las output=ground method=mean class_filter=2
</pre></div>

Set vertical extent of computational region to (relative) coordinates
above ground:

<div class="code"><pre>
g.region rast=secref b=0 t=47 -p3
</pre></div>

Compute point density:

<div class="code"><pre>
r3.in.lidar input=points.las n=points_n sum=points_sum \
    mean=points_mean proportional_n=points_n_prop \
    proportional_sum=points_sum_prop \
    base_raster=ground
</pre></div>


<h3>Complete workflow for vertical structure analysis</h3>
<!-- TODO: needs review and pictures -->
Compute the point density of points in 2D while setting the output
extent to be based on the data (<b>-e</b>) and the resolution set to
a relatively high number (here 10 map units, i.e. meters for
metric projections).

<div class="code"><pre>
r.in.lidar input=points.las output=points_n method=n -e resolution=10
</pre></div>

This step can be repeated with using different resolutions (and the
<b>--overwrite</b> flag) to determine the resolution for the further
analysis.

<p>
The <b>class_filter</b> option should be also provided if only part of
the points is analyzed, for example <tt>class_filter=3,4,5</tt> would be
used for low, medium, and high vegetation if the LAS file follows the
usedstandard ASPRS class numbers.

<p>
The resolution should be suitable for computing digital elevation model
which will be computed in the next steps.
Once you decided on the resolution, you can use the 2D raster to set the
computational region extent and resolution:

<div class="code"><pre>
g.region raster=points_n -p3
</pre></div>

<tt>class_filter=2</tt> is used to limit 

<div class="code"><pre>
r.in.lidar input=points.las output=ground_mean method=mean class_filter=2
</pre></div>

The following steps are not necessary if the point density is high
enough to fill the raster continuously.

<p>
Convert the raster to vector point resulting in a decimated point cloud:

<div class="code"><pre>
v.to.rast input=ground_mean type=point output=ground_decimated use=z
</pre></div>

Interpolate the ground surface from the decimated ground points:

<div class="code"><pre>
v.surf.rst input=ground_decimated elevation=ground
</pre></div>

Now we need to determine upper vertical limit for the 3D raster
(the top value from <tt>g.region -p3</tt>). This can be potentially
done with lower resolution. The <b>-d</b> flag ensures that the ground
raster will be used in its actual resolution regardless of the
resolution of the output.

<div class="code"><pre>
r.in.lidar input=points.las method=max output=veg_max class_filter=3,4,5 base_raster=ground -d
</pre></div>

With that, we can finally set up the 3D extent and resolution:

<div class="code"><pre>
g.region rast=secref b=0 t=40 res=1 res3=1 -p3
</pre></div>

Note that the 2D and 3D resolutions are separate so that user can
perform the 2D calculations on a finer resolution than the 3D
calculations. The vertical resolution can be and often is set to a
different value as well. Here we use the same value for all resolutions
for simplicity.

<p>
Finally, we perform the 3D binning where we count number of points per
cell (voxel):

<div class="code"><pre>
r3.in.lidar input=points.las n=n class_filter=3,4,5 base_raster=ground -d
</pre></div>


<h2>SEE ALSO</h2>

<em>
<a href="r3.in.xyz.html">r3.in.xyz</a>,
<a href="r.in.lidar.html">r.in.lidar</a>,
<a href="v.in.lidar.html">v.in.lidar</a>,
<a href="r.to.rast3.html">r.to.rast3</a>,
<a href="r3.to.rast.html">r3.to.rast</a>,
<a href="r3.mapcalc.html">r3.mapcalc</a>,
<a href="g.region.html">g.region</a>
</em>


<h2>REFERENCES</h2>

<ul>
<li>
V. Petras, A. Petrasova, J. Jeziorska, H. Mitasova (2016):
<em>Processing UAV and lidar point clouds in GRASS GIS</em>.
XXIII ISPRS Congress 2016
[<a href="https://doi.org/10.5194/isprs-archives-XLI-B7-945-2016">ISPRS Archives</a>,
<a href="https://www.researchgate.net/publication/304340172_Processing_UAV_and_lidar_point_clouds_in_GRASS_GIS">ResearchGate</a>]
<li>
<a href="https://www.asprs.org/committee-general/laser-las-file-format-exchange-activities.html">
ASPRS LAS format</a>
<li>
<a href="http://www.liblas.org/">LAS library</a>
<li>
<a href="http://test.liblas.org/doxygen/liblas_8h.htm">LAS library C API</a> documentation
</ul>

<h2>AUTHOR</h2>

Vaclav Petras, <a href="https://geospatial.ncsu.edu/geoforall/">NCSU GeoForAll Lab</a>

<!--
<p>
<i>Last changed: $Date$</i>
-->
